PEP 796: Relative Virtual Environments #4476

rickeylev · 2025-06-30T17:57:23Z

Basic requirements (all PEP Types)

Standards Track requirements

Work towards python/cpython#136051

📚 Documentation preview 📚: https://pep-previews--4476.org.readthedocs.build/

.github/CODEOWNERS

hugovk · 2025-06-30T19:11:53Z

Hello, before we go any further with this PR, has the idea been discussed on Discourse?

And after that we'll need a sponsor before assigning the PEP number, do you have one yet? Let's unassign 796 for now.

Please see:

rickeylev · 2025-06-30T20:42:41Z

Thanks @hugovk and @StanFromIreland for the early review. I used a draft PR to see the CI results to further clean it up -- my apologies for wasting some of your time, but thank you regardless.

discussed on Discourse?

Yes: https://discuss.python.org/t/making-venvs-relocatable-friendly/96177

The criteria of "discussed enough with enough support" is vague, but what gave me enough confidence to begin a PEP and start a (draft) PR at this point was:

The thread didn't go totally off the rails (i.e. voracious disapproval)
Positive statements from @ncoghlan in https://discuss.python.org/t/making-venvs-relocatable-friendly/96177/21 and gh-135773: have pyvenv.cfg without home key anchor a venv and deduce home cpython#135831 (comment)

Sponsor needed to assign number

Thanks for clarifying that part! Yes, finding a sponsor is my next big step.

hugovk · 2025-06-30T21:30:41Z

I used a draft PR to see the CI results to further clean it up

Tip: you can enable GitHub Actions at https://github.com/rickeylev/peps/actions and run the CI on your fork.

Yes, finding a sponsor is my next big step.

Good luck!

…-venv section

peps/pep-0796.rst

AA-Turner · 2025-08-06T00:20:40Z

@paveldikov thank you for the comment, please could you re-post it on Discourse? The peps repo / PR discussion is mainly for editorial discussion, rather than substantive comment on the proposal itself.

A

Co-authored-by: Hugo van Kemenade <[email protected]> Co-authored-by: Zanie Blue <[email protected]>

…envs

…to relative.venvs

rickeylev

Thanks for the reviews! I'm out from under $dayJob and vacation backlogs a bit now and addressed comments.

peps/pep-0796.rst

StanFromIreland

Some little notes

peps/pep-0796.rst

ncoghlan · 2025-08-18T14:54:06Z

Belatedly removed the DO-NOT-MERGE label (that was added pending the Discourse discussion and sponsorship of the PEP)

AA-Turner

The PEP is currently missing a Security Implications section, which I think should be added given that arbitrary directory traversal is permitted -- at the very least explaining why this is fine.

Several editorial notes, I think the Motivation & Rationale sections should be strengthened to focus on the benefits from relative environments, there is currently (I believe) a lot of assumed context.

The PEP also discusses at some length a broader proposal for reloacatable venvs. Is it worth considering making that the proposal here? I don't know the specifics, so it might be that the changes needed for 'relocatable' are too large to tackle in one go.

A

peps/pep-0796.rst

Co-authored-by: Alyssa Coghlan <[email protected]> Co-authored-by: Adam Turner <[email protected]> Co-authored-by: Stan Ulbrych <[email protected]>

rickeylev

Applied suggestions and addressed a few comments; didn't have time to address everything, though.

peps/pep-0796.rst

rickeylev

Ok, all pending comments addressed (I think. The Github UI frequently tricks me 😂 )

PTAL

re: security section: added. At least, insofar as I understand your concern correctly.

re: motivation and rationale strengthening: Thanks! Yeah, honestly, a big issue I've had writing this that "Motivation" and "Rationale" are, to me at least, practically synonyms. I did my best to better separate "Why do this change at all?" (motivation) and "Implementation decision and why that decision" (rationale).

re: proposing relocatable venv in this pep: I added a section about why this pep limits its scope to just the core interpreter.

peps/pep-0796.rst

ncoghlan

A few editorial comments inline, but I think this is essentially ready for publication.

ncoghlan · 2025-09-30T01:48:31Z

peps/pep-0796.rst

+code in that virtual environment. Currently, this path is required to be
+absolute for correct virtual environment operation because the original
+`PEP 405 <https://peps.python.org/pep-0405/>`__
+specifying virtual environments didn't cover any specific way of processing
+relative paths, their behaviour is implementation dependent. CPython releases


Adjusting a run-on sentence:

Suggested change

code in that virtual environment. Currently, this path is required to be

absolute for correct virtual environment operation because the original

`PEP 405 <https://peps.python.org/pep-0405/>`__

specifying virtual environments didn't cover any specific way of processing

relative paths, their behaviour is implementation dependent. CPython releases

code in that virtual environment. Currently, this path is required to be

absolute for consistent virtual environment operation (the original

`PEP 405 <https://peps.python.org/pep-0405/>`__

specifying virtual environments didn't cover any specific way of processing

relative paths, so their behaviour is implementation dependent). CPython releases

ncoghlan · 2025-09-30T01:50:24Z

peps/pep-0796.rst

+Portable virtual environments are important for the efficiency and
+reproducibility benefits they bring from being created once and reused multiple
+times later in different locations. For example, a build farm can build a
+virtual environment once, cache it, and then re-use it as-is to CI jobs.


Suggested change

virtual environment once, cache it, and then re-use it as-is to CI jobs.

virtual environment once, cache it, and then re-use it as-is to run CI jobs.

ncoghlan · 2025-09-30T01:52:21Z

peps/pep-0796.rst

+Fullying designing portable virtual environments
+------------------------------------------------


Suggested change

Fullying designing portable virtual environments

------------------------------------------------

Deferring the design of fully portable virtual environments

-----------------------------------------------------------

ncoghlan · 2025-09-30T01:52:49Z

peps/pep-0796.rst

+
+This PEP purposely only focuses on the interpreter startup behavior to limit
+its scope. There are multiple implementations and many design questions for how
+to implement portable virtual environments work (e.g. what installers should


Suggested change

to implement portable virtual environments work (e.g. what installers should

to fully implement portable virtual environments (e.g. what installers should

ncoghlan · 2025-09-30T02:02:50Z

peps/pep-0796.rst

+During interpreter startup (i.e. :file:`getpath.py`), the relative path is joined to the
+directory containing ``pyvenv.cfg`` to form an absolute path.
+Parent-directory references (``../``) and current
+directory references (``./``) are resolved syntactically (i.e. not resolving


Suggested change

directory references (``./``) are resolved syntactically (i.e. not resolving

directory references (``./``) are resolved lexically (i.e. not resolving

(I don't mind if this isn't accepted, I've just always referred to this style of resolution as lexical rather than as syntactic: python/cpython#124825

ncoghlan · 2025-09-30T02:03:37Z

peps/pep-0796.rst

+
+Currently, relative paths resolve relative to the process's current working
+directory. Because the current working directory isn't knowable in advance, it
+makes relative paths today effectively impossible.


Suggested change

makes relative paths today effectively impossible.

makes using relative paths today effectively impossible.

ncoghlan · 2025-09-30T02:08:18Z

peps/pep-0796.rst

+
+This PEP does not specify how to create a ``pyvenv.cfg`` with a relative path,
+nor how downstream tools (e.g. installers) should identify them or process
+them. These questions are best addressed separately by tool owners.


This isn't an open issue, but rather than intentional omission. Perhaps just include a variant of this paragraph in the rationale subsection about not fully specifying portable virtual environments?

hugovk · 2025-09-30T08:37:04Z

peps/pep-0796.rst

+determine the actual Python interpreter installation that is used to execute
+code in that virtual environment. Currently, this path is required to be
+absolute for correct virtual environment operation because the original
+`PEP 405 <https://peps.python.org/pep-0405/>`__


Lint fix:

Suggested change

`PEP 405 <https://peps.python.org/pep-0405/>`__

:pep:`405`

hugovk · 2025-09-30T08:56:03Z

peps/pep-0796.rst

+machines do so either by relying on undocumented interpreter behaviour
+(Bazel, omitting the ``home`` key entirely to trigger an implementation
+dependent fallback to resolving via a symlinked interpreter binary on
+non-Windows systems, see `gh-135773`) or by requiring a post-installation script to be executed


~~Lint fix:~~

Alyssa's suggestion below is better.

hugovk · 2025-09-30T09:07:48Z

peps/pep-0796.rst

+``PYTHONHOME``.
+A portable virtual environment is one that can be moved between
+platform-compatible hosts, which is an important feature for some projects (see
+"Why portable environments matter").


We can link it:

Suggested change

"Why portable environments matter").

`Why portable virtual environments matter`_).

hugovk · 2025-09-30T09:10:41Z

peps/pep-0796.rst

+
+The reason to support a relative path is to support portable virtual
+environments, which rely on using a host-agnostic relative path to point to
+``PYTHONHOME``.


There's a role for env vars as well, which will link them to the docs:

Suggested change

``PYTHONHOME``.

:envvar:`PYTHONHOME`.

Can also update the other instances below if you like.

Re: https://devguide.python.org/documentation/markup/#information-units

hugovk · 2025-09-30T09:12:20Z

peps/pep-0796.rst

+after the environment is placed in its target location (
+`venvstacks <https://lmstudio.ai/blog/venvstacks#publishing-environment-layer-archives>`__
+).


Remove spaces from inside parentheses:

Suggested change

after the environment is placed in its target location (

`venvstacks <https://lmstudio.ai/blog/venvstacks#publishing-environment-layer-archives>`__

).

after the environment is placed in its target location (`venvstacks

<https://lmstudio.ai/blog/venvstacks#publishing-environment-layer-archives>`__).

hugovk · 2025-09-30T09:17:34Z

peps/pep-0796.rst

+How to Teach This
+=================
+
+Teaching this should be straightforward: if you use a relative path in
+``pyvenv.cfg``, then it's relative to the directory containing the
+``pyvenv.cfg`` file. This is simple to explain and easy to understand for
+anyone that is already familiar with handling relative filesystem paths.


It might be useful to say where you will teach this. What docs will you update?

hugovk · 2025-09-30T09:19:26Z

peps/pep-0796.rst

+  Python runtime.
+* `PoC for relative home in Python startup <https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__
+* `Python Ideas "Making venvs relocatable friendly" discussion <https://discuss.python.org/t/making-venvs-relocatable-friendly/96177>`__
+* `gh-136051: relative pyvenv.cfg home <https://github.com/python/cpython/issues/136051>`__


Can be removed now there's an inline link above.

Suggested change

* `gh-136051: relative pyvenv.cfg home <https://github.com/python/cpython/issues/136051>`__

hugovk · 2025-09-30T09:20:53Z

peps/pep-0796.rst

+paths.
+
+A proof-of-concept of this is implemented in the author's branch,
+`rickeylev/feat.relative.pyvenv.home <https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__.


Suggested change

`rickeylev/feat.relative.pyvenv.home <https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__.

`rickeylev/feat.relative.pyvenv.home

<https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__.

Please could you also wrap some of the other long lines to 79 chars?

https://peps.python.org/pep-0012/#general

hugovk · 2025-09-30T09:22:53Z

peps/pep-0796.rst

+* `venvstacks <https://pypi.org/project/venvstacks/>`__: a tool for creating
+  reproducible distribution artifacts from virtual environments A relocatable
+  Python runtime.
+* `PoC for relative home in Python startup <https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__


This is already linked in the reference implementation section.

Suggested change

* `PoC for relative home in Python startup <https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__

hugovk · 2025-09-30T09:23:20Z

peps/pep-0796.rst

+  host-relocatable virtual environments.
+* `python-build-standalone <https://github.com/astral-sh/python-build-standalone>`__
+* `venvstacks <https://pypi.org/project/venvstacks/>`__: a tool for creating
+  reproducible distribution artifacts from virtual environments A relocatable


Suggested change

reproducible distribution artifacts from virtual environments A relocatable

reproducible distribution artifacts from virtual environments. A relocatable

ncoghlan

I think these are the two items the PEP linter is picking up.

ncoghlan · 2025-09-30T02:13:08Z

peps/pep-0796.rst

+absolute for correct virtual environment operation because the original
+`PEP 405 <https://peps.python.org/pep-0405/>`__


Suggested change

absolute for correct virtual environment operation because the original

`PEP 405 <https://peps.python.org/pep-0405/>`__

absolute for correct virtual environment operation because the original :pep:`405`

ncoghlan · 2025-09-30T02:15:58Z

peps/pep-0796.rst

+machines do so either by relying on undocumented interpreter behaviour
+(Bazel, omitting the ``home`` key entirely to trigger an implementation
+dependent fallback to resolving via a symlinked interpreter binary on
+non-Windows systems, see `gh-135773`) or by requiring a post-installation script to be executed


Suggested change

non-Windows systems, see `gh-135773`) or by requiring a post-installation script to be executed

non-Windows systems, see :cpython-issue:`135773`) or by requiring a post-installation script to be executed

rickeylev added 16 commits June 27, 2025 21:08

initial file

ceeaa3b

add some core content

d0a9289

rename to motivation

41d2ea8

note it enables more advanced optimizations

65a415c

add foot notes, relocatable term section, links

4175b20

update discussion, sponsor headers to pending

bbc85b7

rst fixups

a0c2529

fixup italics

8e6e21e

rename to relative-venv

37202ca

clarify advanced deployment options, reflow some text

b81c50f

add specification, rationale section; doc why env vars arent an option

55a5e28

also mention curdir syntax handling

e09b00d

update some todo text

c7a6a9b

update codeowners

bc1ffbd

add initial discussion footnote link

2301d2a

add fr footnote

e14b01f

rickeylev mentioned this pull request Jun 30, 2025

Support relative home in pyvenv.cfg (host-relocatable venv) python/cpython#136051

Open

StanFromIreland reviewed Jun 30, 2025

View reviewed changes

.github/CODEOWNERS Outdated Show resolved Hide resolved

hugovk added the DO-NOT-MERGE label Jun 30, 2025

hugovk changed the title ~~PEP 796: relative virtual environments, initial draft~~ PEP xxx: relative virtual environments, initial draft Jun 30, 2025

revert codeowners change

175f378

rickeylev added 6 commits July 1, 2025 18:17

remove packaging-related specs

31cb756

fix lint errors with headers

cd46f4d

set sponsor

b532f5c

set sponsor as codeowner

99434fc

clarify title to focus on core pyvenv.cfg home behavior

862142a

fix typo; remove host-relocatable mention; remove non-germane copying…

1c8fb2d

…-venv section

zanieb reviewed Jul 6, 2025

View reviewed changes

peps/pep-0796.rst Outdated Show resolved Hide resolved

zanieb reviewed Jul 6, 2025

View reviewed changes

peps/pep-0796.rst Outdated Show resolved Hide resolved

zanieb reviewed Jul 6, 2025

View reviewed changes

peps/pep-0796.rst Outdated Show resolved Hide resolved

hugovk reviewed Jul 11, 2025

View reviewed changes

aignas mentioned this pull request Jul 24, 2025

feat(core): switch to script bootstrap as a default bazel-contrib/rules_python#3117

Open

1 task

Vigilans mentioned this pull request Jul 28, 2025

Support copy or hardlink python interpreter when creating venv astral-sh/uv#6782

Open

This comment has been minimized.

Sign in to view

rickeylev and others added 4 commits August 17, 2025 13:02

Apply suggestions from code review

5b259cc

Co-authored-by: Hugo van Kemenade <[email protected]> Co-authored-by: Zanie Blue <[email protected]>

Merge branch 'main' of https://github.com/python/peps into relative.v…

560dadb

…envs

Merge branch 'relative.venvs' of https://github.com/rickeylev/peps in…

f41ed51

…to relative.venvs

better answer why/how relvenvs help; wrap some long lines

5cbc9f5

rickeylev commented Aug 17, 2025

View reviewed changes

peps/pep-0796.rst Outdated Show resolved Hide resolved

peps/pep-0796.rst Outdated Show resolved Hide resolved

StanFromIreland reviewed Aug 18, 2025

View reviewed changes

peps/pep-0796.rst Outdated Show resolved Hide resolved

peps/pep-0796.rst Outdated Show resolved Hide resolved

peps/pep-0796.rst Outdated Show resolved Hide resolved

peps/pep-0796.rst Outdated Show resolved Hide resolved

ncoghlan removed the DO-NOT-MERGE label Aug 18, 2025

AA-Turner requested changes Aug 18, 2025

View reviewed changes

AA-Turner changed the title ~~PEP 796: relative virtual environments, initial draft~~ PEP 796: Relative Virtual Environments [initial draft] Aug 18, 2025

rickeylev and others added 2 commits August 20, 2025 22:12

Apply AA-Turner suggestions

0af0eea

Co-authored-by: Alyssa Coghlan <[email protected]> Co-authored-by: Adam Turner <[email protected]> Co-authored-by: Stan Ulbrych <[email protected]>

add refs, remove CWD acronym, fix grammar

68dd5e0

rickeylev commented Aug 21, 2025

View reviewed changes

peps/pep-0796.rst Outdated Show resolved Hide resolved

peps/pep-0796.rst Outdated Show resolved Hide resolved

peps/pep-0796.rst Outdated Show resolved Hide resolved

peps/pep-0796.rst Outdated Show resolved Hide resolved

peps/pep-0796.rst Outdated Show resolved Hide resolved

address review comments: better split and organize rationale/motivation

b50a80c

rickeylev commented Aug 24, 2025

View reviewed changes

rickeylev mentioned this pull request Sep 6, 2025

Implement venv support for bootstrap system_python bazel-contrib/rules_python#3245

Open

AA-Turner added the new-pep A new draft PEP submitted for initial review label Sep 29, 2025

Merge branch 'main' into relative.venvs

af8f880

ncoghlan approved these changes Sep 30, 2025

View reviewed changes

hugovk changed the title ~~PEP 796: Relative Virtual Environments [initial draft]~~ PEP 796: Relative Virtual Environments Sep 30, 2025

hugovk reviewed Sep 30, 2025

View reviewed changes

ncoghlan reviewed Sep 30, 2025

View reviewed changes

	virtual environment once, cache it, and then re-use it as-is to CI jobs.
	virtual environment once, cache it, and then re-use it as-is to run CI jobs.

		Fullying designing portable virtual environments
		------------------------------------------------

	to implement portable virtual environments work (e.g. what installers should
	to fully implement portable virtual environments (e.g. what installers should

	directory references (``./``) are resolved syntactically (i.e. not resolving
	directory references (``./``) are resolved lexically (i.e. not resolving

	makes relative paths today effectively impossible.
	makes using relative paths today effectively impossible.

	"Why portable environments matter").
	`Why portable virtual environments matter`_).

	`rickeylev/feat.relative.pyvenv.home <https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__.
	`rickeylev/feat.relative.pyvenv.home
	<https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__.

	reproducible distribution artifacts from virtual environments A relocatable
	reproducible distribution artifacts from virtual environments. A relocatable

		absolute for correct virtual environment operation because the original
		`PEP 405 <https://peps.python.org/pep-0405/>`__

	non-Windows systems, see `gh-135773`) or by requiring a post-installation script to be executed
	non-Windows systems, see :cpython-issue:`135773`) or by requiring a post-installation script to be executed

Uh oh!

PEP 796: Relative Virtual Environments #4476

Are you sure you want to change the base?

PEP 796: Relative Virtual Environments #4476

Uh oh!

Conversation

rickeylev commented Jun 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Basic requirements (all PEP Types)

Standards Track requirements

Uh oh!

Uh oh!

hugovk commented Jun 30, 2025

Uh oh!

rickeylev commented Jun 30, 2025

Uh oh!

hugovk commented Jun 30, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

AA-Turner commented Aug 6, 2025

Uh oh!

rickeylev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ncoghlan commented Aug 18, 2025

Uh oh!

AA-Turner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rickeylev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rickeylev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ncoghlan left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

rickeylev commented Jun 30, 2025 •

edited

Loading

ncoghlan left a comment •

edited

Loading

hugovk Sep 30, 2025 •

edited

Loading